Cognitive Brownbag

Holly Zaharchuk

February 19, 2020

What is R Markdown?

  • Markup language
  • R Markdown != R

Parts of a Markdown document

  1. YAML header
  2. Markdown language
  3. Code chunks

YAML header

Global options for outputs/formatting

YAML example

Markdown

Plain text formatting allows for conversion to multiple document types

Markdown example

Chunks

# This is a chunk of R code that adds an image
knitr::include_graphics("images/example_chunk.png")

Creating output

Output types

  • PDF: requires \(\LaTeX\) to compile (see TinyTeX distribution)
  • HTML
  • Microsoft Office (Word/Powerpoint)

YAML specification

  • Use output argument in YAML header
  • Pay attention to indentation and colons
  • Press knit button or command/CTRL-shift-K

Render

  • Render file in console: rmarkdown::render(file, output_format)
  • Option to create PDF from HTML: pagedown::chrome_print(file)

Using output templates

  1. Built-in templates
  2. Templates from R packages
  3. User-defined templates

Built-in templates

  • Presentations
    • ioslides and Slidy for HTML
    • Beamer for PDF
  • Shiny documents and presentations (interactive)

R packages

User-defined templates

\(\LaTeX\) templates LaTeX example

User-defined templates

Word Document Word example

Formatting

  1. YAML parameters and references
  2. Inline \(\LaTeX\) and CSS code
  3. Custom edits to template documents

YAML parameters

YAML references

These files go in the same place as your .Rmd

  • Bibliography: .bib (I use BibDesk for my reference manager)
  • Bibiography style: .csl (see my CV and Psychonomics poster repos for APA 6 files)
  • \(\LaTeX\) styling: .cls
  • HTML styling: .css
  • Interacting with pandoc: .lua (multiple bibliographies)

Inline \(\LaTeX\)  and CSS code

  • \(\LaTeX\) with PDFs
    • Calling \(\LaTeX\) packages
    • Using symbols: here and here
    • Using type-setting commands (e.g., \vspace{12pt})
  • CSS with HTML

\(\LaTeX\)

Examples from my stats homework

Packages Calls

\(\LaTeX\)

LaTeX example output

CSS/HTML

Examples from my Psychonomics poster

CSS formatting example HTML formatting example

Editing template documents

# Make dataframe with installed packages
pkgs <- installed.packages() %>%
  as.data.frame()

# Pull posterdown package 
pstr <- pkgs %>% 
  select(Package, LibPath, Version, Depends, Imports) %>%
  dplyr::filter(Package == "posterdown")

# Make table
kable(pstr) %>%
  kable_styling(bootstrap_options = "condensed", 
                font_size = 18)
Package LibPath Version Depends Imports
posterdown /Library/Frameworks/R.framework/Versions/3.5/Resources/library 1.0 NA pagedown, rmarkdown, yaml

Editing template documents

  • Save the original template and move it to a different location
  • Make one change at a time
  • Name the updated template with the same name in the same place as the original

Trouble-shooting

Identifying issues

  • Warnings vs. errors
  • Console vs. chunk
  • Markdown environment vs. R environment
  • Package specification :: for unloaded packages and conflicts

Warnings

Warnings won’t stop your document from compiling, but generally indicate that you should change something in your code

Warning example

Errors

Chunk error Error example

Markdown/YAML error Error example

R code and environments

Running a chunk executes the code in the console and adds the output to your R environment

R code and environments

Your R environment is separate from the environment created by “knitting” a document

y <- 100
# print(x + y) works when I run this chunk, but fails when knitting
print(y)
## [1] 100

Tips

  • Clear all variables: rm(ls = list())
  • Restart R environment: control/CTRL + fn + shift + F10
  • Run all chunks individually in order before compiling to test code
  • Google package and error

Stack Overflow is your friend!

Reference documents

Random tidbits

  • Escape characters with a backslash \
  • Call R objects in Markdown by ~sandwiching~ with backticks ``
  • Automatic bracket/quote/asterisk wrapping
  • Dollar signs for \(\LaTeX\) math mode (but also be careful with pandoc)
  • Line spacing matters in markup

Other packages/tools

Updating software/packages

  • Update your TeX distribution from the command line
  • Update all packages (including rmarkdown) in library with update.packages(path)
  • Update individual packages by reinstalling with install.packages(package)
  • Update R in the console with updateR package
  • Redownload RStudio to update

R Stuff

  • Regular expressions for working with free response text (cheat sheet here)
  • assign() function for dynamic variable names
  • Store ggplot parameters in a list()
  • source()
  • %notin%

Keys to success

  • Data are read only
  • Comment your code excessively
  • Keep chunks small